<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>selection manual page - Tk Built-In Commands</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tk Commands</a> <small>&gt;</small> selection</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<DL>
<DD><A HREF="selection.htm#M2" NAME="L1374">NAME</A>
<DL><DD>selection &mdash; Manipulate the X selection</DD></DL>
<DD><A HREF="selection.htm#M3" NAME="L1375">SYNOPSIS</A>
<DL>
</DL>
<DD><A HREF="selection.htm#M4" NAME="L1376">DESCRIPTION</A>
<DL class="description">
<DD><A HREF="selection.htm#M5" NAME="L1377"><B>selection clear</B> ?<B>-displayof</B> <I>window</I>? ?<B>-selection</B> <I>selection</I>?</A>
<DD><A HREF="selection.htm#M6" NAME="L1378"><B>selection get</B> ?<B>-displayof</B> <I>window</I>? ?<B>-selection</B> <I>selection</I>? ?<B>-type</B> <I>type</I>?</A>
<DD><A HREF="selection.htm#M7" NAME="L1379"><B>selection handle</B> ?<B>-selection</B> <I>s</I>? ?<B>-type</B> <I>t</I>? ?<B>-format</B> <I>f</I>? <I>window command</I></A>
<DD><A HREF="selection.htm#M8" NAME="L1380"><B>selection own</B> ?<B>-displayof</B> <I>window</I>? ?<B>-selection</B> <I>selection</I>?</A>
<DD><A HREF="selection.htm#M9" NAME="L1381"><B>selection own</B> ?<B>-command</B> <I>command</I>? ?<B>-selection</B> <I>selection</I>? <I>window</I></A>
</DL>
<DD><A HREF="selection.htm#M10" NAME="L1382">WIDGET FACILITIES</A>
<DD><A HREF="selection.htm#M11" NAME="L1383">PORTABILITY ISSUES</A>
<DD><A HREF="selection.htm#M12" NAME="L1384">SECURITY</A>
<DD><A HREF="selection.htm#M13" NAME="L1385">EXAMPLES</A>
<DD><A HREF="selection.htm#M14" NAME="L1386">SEE ALSO</A>
<DD><A HREF="selection.htm#M15" NAME="L1387">KEYWORDS</A>
</DL>
<H3><A NAME="M2">NAME</A></H3>
selection &mdash; Manipulate the X selection
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>selection </B><I>option</I> ?<I>arg arg ...</I>?<BR>
<H3><A NAME="M4">DESCRIPTION</A></H3>
This command provides a Tcl interface to the X selection mechanism and
implements the full selection functionality described in the
X Inter-Client Communication Conventions Manual (ICCCM).
<P>
Note that for management of the <B>CLIPBOARD</B> selection (see below), the
<B><A HREF="../TkCmd/clipboard.htm">clipboard</A></B> command may also be used.
<P>
The first argument to <B>selection</B> determines the format of the
rest of the arguments and the behavior of the command.  The following
forms are currently supported:
<P>
<DL class="description">
<DT><A NAME="M5"><B>selection clear</B> ?<B>-displayof</B> <I>window</I>? ?<B>-selection</B> <I>selection</I>?</A><DD>
If <I>selection</I> exists anywhere on <I>window</I>'s display, clear it
so that no window owns the selection anymore.  <I>Selection</I>
specifies the X selection that should be cleared, and should be an
atom name such as <B>PRIMARY</B> or <B>CLIPBOARD</B>; see the Inter-Client
Communication Conventions Manual for complete details.
<I>Selection</I> defaults to <B>PRIMARY</B> and <I>window</I> defaults to
&ldquo;.&rdquo;.
Returns an empty string.
<P><DT><A NAME="M6"><B>selection get</B> ?<B>-displayof</B> <I>window</I>? ?<B>-selection</B> <I>selection</I>? ?<B>-type</B> <I>type</I>?</A><DD>
Retrieves the value of <I>selection</I> from <I>window</I>'s display and
returns it as a result.  <I>Selection</I> defaults to <B>PRIMARY</B> and
<I>window</I> defaults to
&ldquo;.&rdquo;.
<I>Type</I> specifies the form in which the selection is to be returned
(the desired
&ldquo;target&rdquo;
for conversion, in ICCCM terminology), and
should be an atom name such as <B>STRING</B> or <B>FILE_NAME</B>; see the
Inter-Client Communication Conventions Manual for complete details.
<I>Type</I> defaults to <B>STRING</B>.  The selection owner may choose to
return the selection in any of several different representation
formats, such as <B>STRING</B>, <B>UTF8_STRING</B>, <B>ATOM</B>,
<B>INTEGER</B>, etc. (this format is different
than the selection type; see the ICCCM for all the confusing details).
If the selection is returned in a non-string format, such as <B>INTEGER</B>
or <B>ATOM</B>, the <B>selection</B> command converts it to string format as a
collection of fields separated by spaces: atoms are converted to their
textual names, and anything else is converted to hexadecimal integers.
Note that <B>selection get</B> does not retrieve the selection in the
<B>UTF8_STRING</B> format unless told to.
<P><DT><A NAME="M7"><B>selection handle</B> ?<B>-selection</B> <I>s</I>? ?<B>-type</B> <I>t</I>? ?<B>-format</B> <I>f</I>? <I>window command</I></A><DD>
Creates a handler for selection requests, such that <I>command</I> will
be executed whenever selection <I>s</I> is owned by <I>window</I> and
someone attempts to retrieve it in the form given by type <I>t</I>
(e.g. <I>t</I> is specified in the <B>selection get</B> command).
<I>S</I> defaults to <B>PRIMARY</B>, <I>t</I> defaults to <B>STRING</B>, and
<I>f</I> defaults to <B>STRING</B>.  If <I>command</I> is an empty string
then any existing handler for <I>window</I>, <I>t</I>, and
<I>s</I> is removed.
Note that when the selection is handled as type <B>STRING</B> it is also
automatically handled as type <B>UTF8_STRING</B> as well.
<P>
When <I>selection</I> is requested, <I>window</I> is the selection owner,
and <I>type</I> is the requested type, <I>command</I> will be executed
as a Tcl command with two additional numbers appended to it
(with space separators).
The two additional numbers
are <I>offset</I> and <I>maxChars</I>:  <I>offset</I> specifies a starting
character position in the selection and <I>maxChars</I> gives the maximum
number of characters to retrieve.  The command should return a value consisting
of at most <I>maxChars</I> of the selection, starting at position
<I>offset</I>.  For very large selections (larger than <I>maxChars</I>)
the selection will be retrieved using several invocations of <I>command</I>
with increasing <I>offset</I> values.  If <I>command</I> returns a string
whose length is less than <I>maxChars</I>, the return value is assumed to
include all of the remainder of the selection;  if the length of
<I>command</I>'s result is equal to <I>maxChars</I> then
<I>command</I> will be invoked again, until it eventually
returns a result shorter than <I>maxChars</I>.  The value of <I>maxChars</I>
will always be relatively large (thousands of characters).
<P>
If <I>command</I> returns an error then the selection retrieval is rejected
just as if the selection did not exist at all.
<P>
The <I>format</I> argument specifies the representation that should be
used to transmit the selection to the requester (the second column of
Table 2 of the ICCCM), and defaults to <B>STRING</B>.  If <I>format</I> is
<B>STRING</B>, the selection is transmitted as 8-bit ASCII characters (i.e.
just in the form returned by <I>command</I>, in the system <B><A HREF="../TclCmd/encoding.htm">encoding</A></B>;
the <B>UTF8_STRING</B> format always uses UTF-8 as its encoding).
If <I>format</I> is
<B>ATOM</B>, then the return value from <I>command</I> is divided into fields
separated by white space;  each field is converted to its atom value,
and the 32-bit atom value is transmitted instead of the atom name.
For any other <I>format</I>, the return value from <I>command</I> is
divided into fields separated by white space and each field is
converted to a 32-bit integer;  an array of integers is transmitted
to the selection requester.
<P>The <I>format</I> argument is needed only for compatibility with
selection requesters that do not use Tk.  If Tk is being
used to retrieve the selection then the value is converted back to
a string at the requesting end, so <I>format</I> is
irrelevant.
<P><DT><A NAME="M8"><B>selection own</B> ?<B>-displayof</B> <I>window</I>? ?<B>-selection</B> <I>selection</I>?</A><DD>
<P><DT><A NAME="M9"><B>selection own</B> ?<B>-command</B> <I>command</I>? ?<B>-selection</B> <I>selection</I>? <I>window</I></A><DD>
The first form of <B>selection own</B> returns the path name of the
window in this application that owns <I>selection</I> on the display
containing <I>window</I>, or an empty string if no window in this
application owns the selection.  <I>Selection</I> defaults to <B>PRIMARY</B> and
<I>window</I> defaults to
&ldquo;.&rdquo;.
<P>
The second form of <B>selection own</B> causes <I>window</I> to become
the new owner of <I>selection</I> on <I>window</I>'s display, returning
an empty string as result. The existing owner, if any, is notified
that it has lost the selection.
If <I>command</I> is specified, it is a Tcl script to execute when
some other window claims ownership of the selection away from
<I>window</I>.  <I>Selection</I> defaults to PRIMARY.
<P></DL>
<H3><A NAME="M10">WIDGET FACILITIES</A></H3>
The <B><A HREF="../TkCmd/text.htm">text</A></B>, <B><A HREF="../TkCmd/entry.htm">entry</A></B>, <B><A HREF="../TkCmd/ttk_entry.htm">ttk::entry</A></B>, <B><A HREF="../TkCmd/listbox.htm">listbox</A></B>, <B><A HREF="../TkCmd/spinbox.htm">spinbox</A></B> and <B><A HREF="../TkCmd/ttk_spinbox.htm">ttk::spinbox</A></B> widgets have the option <B>-exportselection</B>.  If a widget has this option set to boolean <B>true</B>, then (in an unsafe interpreter) a selection made in the widget is automatically written to the <B>PRIMARY</B> selection.
<P>
A GUI event, for example <B>&lt;&lt;PasteSelection&gt;&gt;</B>, can copy the <B>PRIMARY</B> selection to certain widgets.  This copy is implemented by a widget binding to the event.  The binding script makes appropriate calls to the <B>selection</B> command.
<P>
<H3><A NAME="M11">PORTABILITY ISSUES</A></H3>
On X11, the <B>PRIMARY</B> selection is a system-wide feature of the X server, allowing communication between different processes that are X11 clients.
<P>
On Windows, the <B>PRIMARY</B> selection is not provided by the system, but only by Tk, and so it is shared only between windows of a parent interpreter and its child interpreters.  It is not shared between interpreters in different processes or different threads.  Each parent interpreter has a separate <B>PRIMARY</B> selection that is shared only with its child interpreters which are not safe interpreters.
<P>
<H3><A NAME="M12">SECURITY</A></H3>
A safe interpreter cannot read from the <B>PRIMARY</B> selection because its <B>selection</B> command is hidden.  For this reason the <B>PRIMARY</B> selection cannot be written to the Tk widgets of a safe interpreter.
<P>
A Tk widget can have its option <B>-exportselection</B> set to boolean <B>true</B>, but in a safe interpreter this option has no effect: writing from the widget to the <B>PRIMARY</B> selection is disabled.
<P>
These are security features.  A safe interpreter may run untrusted code, and it is a security risk if this untrusted code can read or write the <B>PRIMARY</B> selection used by other interpreters.
<P>
<H3><A NAME="M13">EXAMPLES</A></H3>
On X11 platforms, one of the standard selections available is the
<B>SECONDARY</B> selection. Hardly anything uses it, but here is how to read
it using Tk:
<P>
<PRE>set selContents [<B>selection get</B> -selection SECONDARY]</PRE>
<P>
Many different types of data may be available for a selection; the
special type <B>TARGETS</B> allows you to get a list of available types:
<P>
<PRE>foreach type [<B>selection get</B> -type TARGETS] {
   puts &quot;Selection PRIMARY supports type $type&quot;
}</PRE>
<P>
To claim the selection, you must first set up a handler to supply the
data for the selection. Then you have to claim the selection...
<PRE># Set up the data handler ready for incoming requests
set foo &quot;This is a string with some data in it... blah blah&quot;
<B>selection handle</B> -selection SECONDARY . getData
proc getData {offset maxChars} {
   puts &quot;Retrieving selection starting at $offset&quot;
   return [string range $::foo $offset [expr {$offset+$maxChars-1}]]
}

# Now we grab the selection itself
puts &quot;Claiming selection&quot;
<B>selection own</B> -command lost -selection SECONDARY .
proc lost {} {
   puts &quot;Lost selection&quot;
}</PRE>
<H3><A NAME="M14">SEE ALSO</A></H3>
<B><A HREF="../TkCmd/clipboard.htm">clipboard</A></B>
<H3><A NAME="M15">KEYWORDS</A></H3>
<A href="../Keywords/C.htm#clear">clear</A>, <A href="../Keywords/F.htm#format">format</A>, <A href="../Keywords/H.htm#handler">handler</A>, <A href="../Keywords/I.htm#ICCCM">ICCCM</A>, <A href="../Keywords/O.htm#own">own</A>, <A href="../Keywords/S.htm#selection">selection</A>, <A href="../Keywords/T.htm#target">target</A>, <A href="../Keywords/T.htm#type">type</A>
<div class="copy">Copyright &copy; 1990-1994 The Regents of the University of California.
<BR>Copyright &copy; 1994-1996 Sun Microsystems, Inc.
</div>
</BODY></HTML>
